Inside Macintosh: More Macintosh Toolbox
Before a component can be used by an application, the component must be registered with the Component Manager. The Component Manager automatically registers component resources stored in files with file types of 'thng' that are stored in the Extensions folder (for information about the content of component resources, see "Resources," ).
Alternatively, you can use either the RegisterComponent function or the RegisterComponentResource function to register components. Both applications and components can use these routines to register components.
Furthermore, you can use the RegisterComponentResourceFile function to register all components specified in a given resource file.
Once you have registered your component, applications can find the component and retrieve information about it using the Component Manager routines described earlier in this chapter in "Routines for Applications," .
Finally, you can use the UnregisterComponent function to remove a component from the registration list.
When an application quits, the Component Manager automatically closes any component connections to that application. In addition, if the application has registered components that reside in its heap space, the Component Manager automatically unregisters those components.
The RegisterComponent function makes a component available for use by applications (or other clients). Once the Component Manager has registered a component, applications can find and open the component using the standard Component Manager routines. To register a component, you provide information identifying the component and its capabilities. The Component Manager returns a component identifier that uniquely identifies the component to the system.
Components you register with the RegisterComponent function must be in memory when you call this function. If you want to register a component that is stored in the resource fork of a file, use the RegisterComponentResource function. Use the RegisterComponentResourceFile function to register all components in the resource fork of a file.
Note that a component residing in your application heap remains registered until your application unregisters it or quits. A component residing in the system heap and registered by your application remains registered until your application unregisters it or until the computer is shut down.
FUNCTION RegisterComponent (cd: ComponentDescription;
componentEntryPoint: ComponentRoutine;
global: Integer;
componentName: Handle;
componentInfo: Handle;
componentIcon: Handle): Component;
The RegisterComponent function registers the specified component, recording the information specified in the cd , componentName , componentInfo , and componentIcon parameters. The function returns the component identifier assigned to the component by the Component Manager. If it cannot register the component, the RegisterComponent function returns a function result of NIL .
For a complete description of the component description record, see "Data Structures for Components," .
The RegisterComponentResource function makes a component available for use by applications (or other clients). Once the Component Manager has registered a component, applications can find and open the component using the standard Component Manager routines. You provide information identifying the component and specifying its capabilities. The Component Manager returns a component identifier that uniquely identifies the component to the system.
Components you register with the RegisterComponentResource function must be stored in a resource file as a component resource (see "The Component Resource," for a description of the format and content of component resources). If you want to register a component that is in memory, use the RegisterComponent function.
The RegisterComponentResource function does not actually load the code specified by the component resource into memory. Rather, the Component Manager loads the component code the first time an application opens the component. If the code is not in the same file as the component resource or if the Component Manager cannot find the file, the open request fails.
Note that a component registered locally by your application remains registered until your application unregisters it or quits. A component registered globally by your application remains registered until your application unregisters it or until the computer is shut down.
FUNCTION RegisterComponentResource (cr: ComponentResourceHandle;
global: Integer): Component;
The RegisterComponentResource function returns the component identifier assigned to the component by the Component Manager. If the RegisterComponentResource function could not register the component, it returns a function result of NIL .
For a description of the format and content of component resources, see "Resources," .
The RegisterComponentResourceFile function registers all component resources in the given resource file according to the flags specified in the global parameter.
FUNCTION RegisterComponentResourceFile (resRefNum: integer;
global: integer): LongInt;
The RegisterComponentResourceFile function registers components in a resource file. If the RegisterComponentResourceFile function successfully registers all components in the specified resource file, RegisterComponentResourceFile returns a function result that indicates the number of components registered. If the RegisterComponentResourceFile function could not register one or more of the components in the resource file or if the specified file reference number is invalid, it returns a negative function result.
For a description of the format and content of component resources, see "Resources," .
The UnregisterComponent function removes a component from the Component Manager's registration list. Most components are registered at startup and remain registered until the computer is shut down. However, you may want to provide some services temporarily. In that case you dispose of the component that provides the temporary service by using this function.
FUNCTION UnregisterComponent (aComponent: Component): OSErr;
The UnregisterComponent function removes the component with the specified component identifier from the list of available components. The component to be removed from the registration list must not be in use by any applications or components. If there are open connections to the component, the UnregisterComponent function returns a negative result code.
If you provide a component that supports the unregister request, see "Responding to the Register Request" for more information.